List Tasks

List board tasks with optional status and assignment filters

GET /api/boards/{board_id}/tasks

List Tasks

cURL

curl --request GET \
  --url https://api.example.com/api/boards/{board_id}/tasks

200

{
  "items": [
    {
      "id": "<string>",
      "board_id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "status": "<string>",
      "priority": "<string>",
      "due_at": "<string>",
      "assigned_agent_id": "<string>",
      "created_by_user_id": "<string>",
      "in_progress_at": "<string>",
      "depends_on_task_ids": [
        {}
      ],
      "blocked_by_task_ids": [
        {}
      ],
      "is_blocked": true,
      "tag_ids": [
        {}
      ],
      "tags": [
        {}
      ],
      "custom_field_values": {},
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123
}

Retrieve a paginated list of tasks for a specific board, with support for filtering by status, assigned agent, and assignment state.

Path Parameters

board_id · string · required

The UUID of the board to list tasks from

Query Parameters

status · string

Filter tasks by status. Can be comma-separated for multiple statuses.

Allowed values: inbox, in_progress, review, done

Example: status=inbox,in_progress

assigned_agent_id · string

Filter tasks assigned to a specific agent UUID

unassigned · boolean

Filter for unassigned tasks only

limit · integer · default: "50"

Number of results per page

offset · integer · default: "0"

Number of results to skip

Response

items · array

Array of task objects

id · string

Task UUID

board_id · string

Board UUID this task belongs to

title · string

Task title

description · string

Task description (optional)

status · string

Current task status: inbox, in_progress, review, or done

priority · string · default: "medium"

Task priority level

due_at · string

ISO 8601 timestamp for task due date (optional)

assigned_agent_id · string

UUID of the assigned agent (null if unassigned)

created_by_user_id · string

UUID of the user who created the task

in_progress_at · string

ISO 8601 timestamp when task entered in_progress status

depends_on_task_ids · array

Array of task UUIDs this task depends on

blocked_by_task_ids · array

Array of task UUIDs blocking this task (incomplete dependencies)

is_blocked · boolean

Whether this task is blocked by incomplete dependencies

tag_ids · array

Array of tag UUIDs applied to this task

tags · array

Array of tag objects with id, name, and color

custom_field_values · object

Key-value pairs of custom field values

created_at · string

ISO 8601 timestamp of task creation

updated_at · string

ISO 8601 timestamp of last update

total · integer

Total number of tasks matching the filter

limit · integer

Results per page

offset · integer

Results skipped

Example Request

curl -X GET "https://api.openclaw.ai/api/boards/123e4567-e89b-12d3-a456-426614174000/tasks?status=inbox,in_progress&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "board_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Implement user authentication",
      "description": "Add OAuth2 authentication flow with JWT tokens",
      "status": "in_progress",
      "priority": "high",
      "due_at": "2026-03-15T18:00:00Z",
      "assigned_agent_id": "9f8d7c6b-5a4e-3d2c-1b0a-9f8e7d6c5b4a",
      "created_by_user_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "in_progress_at": "2026-03-05T10:30:00Z",
      "depends_on_task_ids": [
        "660e8400-e29b-41d4-a716-446655440001"
      ],
      "blocked_by_task_ids": [],
      "is_blocked": false,
      "tag_ids": [
        "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f"
      ],
      "tags": [
        {
          "id": "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f",
          "name": "backend",
          "color": "#3b82f6"
        }
      ],
      "custom_field_values": {
        "effort_points": 5,
        "sprint": "Sprint 12"
      },
      "created_at": "2026-03-01T09:00:00Z",
      "updated_at": "2026-03-05T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Status Values

Tasks progress through the following statuses:

• inbox: Newly created, unassigned tasks
• in_progress: Task is actively being worked on
• review: Task completed and awaiting review
• done: Task approved and completed

Notes

• Tasks marked as done will never show as blocked, even if dependencies exist
• Use unassigned=true to find tasks available for assignment
• Combine status filters with assignment filters for precise queries
• Custom field values are board-specific and depend on field definitions